Copyright: ® 1996 Kalliopi Intl.  All rights reserved.


Help Contents
Contents

The Security Guard

  TKpSecurityGuard

AutoVerifyAfter Property

CaseSensative Property

ChangePasswordCaption Property

DefaultEncryption Property

EditUserCaption Property

EditUserListCaption Property

Logged Property

LoginCaption Property

NumberOfTries Property

Password Property

PasswordChar Property

PasswordField Property

PasswordLabel Property

SecurityLevel Property

SecurityLevelField Property

SecurityLevelLabel Property

SecurityTable Property

ShowPassword Property

StandardLogFile Property

StandardLogOn Property

Status Property

TStatus Type

User Property

UserField Property

UserLabel Property

Units

AddNewUser Method

ChangePassword Method

ChangeSpecificPassword Method

CheckPassword Method

DeleteSpecificUser Method

DeleteUser Method

DoDefaultEncryption Method

EditSpecificUser Method

EditUser Method

EditUserList Method

LocateUser Method

Log Method

TSecurityEvent Type

LogResFmt Method

LogIn Method

LogOut Method

MainLog Method

UpdatePassword Method

UpdateSecurityLevel Method

UpdateUser Method

VerifyPassword Method

AllowAdd Event

TAllowEvent Type

AllowDelete Event

AllowEdit Event

AllowList Event

OnEncrypt Event

TEncryptEvent Type

OnFailedLogIn Event

TNotifyEvent Type

OnFailedVerify Type

OnSecurityAction Event

TSecurityActionEvent Type

TEventInfo Type

Using the SecurityGuard Component

The Guard List

  TKpGuardList component

Properties

Methods

TSecurityOption Type

Count Property

DefaultProp Property

List Property

SecurityGuard Property

GetRealSecurityOption Method

GetSecurityLevel Method

GetSecurityOption Method

Guard Method

GuardAll Method

IsProtected Method

Protect Method

SetRealSecurityOption Method

SetSecurityLevel Method

Setup Method

ShowList Method

UnProtect Method


  TKpSecurityGuard

Properties	Methods	Events	Tasks

Unit

KpSecure

Description

The TKpSecurityGuard is designed to work with the TKpGuardList to give you complete application security with a few simple lines of code.

The SecurityGuard can LogIn users who need to use the system, and can LogOut users are finished using the system.  Test the logged property to find out if anyone is currently logged into the system.  After AutoVerifyAfter minutes have passed, the SecurityGuard can automatically call the VerifyPassword method to make sure that the correct user is still using the system.  The NumberOfTries property dictates how many times the user can try to LogIn, or Verify his Password.  The PasswordChar property sets what character will be shown when the User types in his password.

The SecurityTable which holds information about your users can be completely specified by you.  You specify the Table, and which fields are to be used to hold the list of Users, Passwords, and SecurityLevels.

To change the password for the current User call the ChangePassword method.  To edit information for just the current user (UserID, Password & SecurityLevel ) call the EditUser method.  To edit the current list of users in the SecurityTable, use EditUserList method.

The caption for each dialog can be set in the LoginCaption, EditUserCaption, EditUserListCaption and ChangePasswordCaption properties.  Names for the Key terms in the system can be set in the UserLabel, PasswordLabel and SecurityLevelLabel properties.  If you change one of these properties, every reference to the term will be changed throughout the system.  For example: if you change Password to PIN, a message which used to read: "Enter Password" would now automatically read "Enter PIN".

When a user FAILS to LogIn to the system, the OnFailedLogIn event will be triggered.  When the user fails to Verify his password, the OnFailedVerify event will be triggered.

For information about SecurityGuard Encryption please refer to the OnEncrypt event and the DefaultEncryption properties.


Properties

Run-time only	Key properties

AutoVerifyAfter	NumberOfTries	SecurityTable

CaseSensative	Password	ShowPassword

ChangePasswordCaption	PasswordChar	StandardLogFile

DefaultEncryption	PasswordField	StandardLogOn

EditUserCaption	PasswordLabel	Status

EditUserListCaption	SecurityLevel	User

Logged	SecurityLevelLabel	UserField

LoginCaption	SecurityLevelField	UserLabel


Methods

Key methods

AddNewUser	EditSpecificUser	LogOut

ChangePassword	EditUser	MainLog

ChangeSpecificPassword	EditUserList	UpdatePassword

CheckPassword	LocateUser	UpdateSecurityLevel

DeleteSpecificUser	Log	UpdateUser

DeleteUser	LogResFmt	VerifyPassword

DoDefaultEncryption	LogIn


Events

Key events

AllowAdd	AllowList	OnFailedVerify

AllowDelete	OnEncrypt	OnSecurityAction

AllowEdit	OnFailedLogIn


AutoVerifyAfter Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property AutoVerifyAfter: integer;

Description

After a user logs into the system with the LogIn method, the SecurityGuard can keep track of how long the user has been logged in.  After the specified number of minutes, the SecurityGuard can automatically call the VerifyPassword method, to make sure that the current user is still the user who originally logged in.

NOTE: Set the AutoVerifyAfter property to 0 to disable.

NOTE:	VerifyPassword will NOT be called unless the Security Guard is At Attention.


Example

The following would cause the SecurityGuard to verify the User's Password every 15 minutes

KpSecurityGuard1.AutoVerifyAfter := 15;


See Also

VerifyPassword Method

LogIn Method


CaseSensative Property

See Also

Applies to

TKpSecurityGuard component

Declaration

property CaseSensative: boolean;

Description

The CaseSensative property is a very important property.  It determines how the SecurityGuard compares strings.  If this property is set to True, then if there are ANY case discrepancies between two strings, these strings will be considered different.

NOTE: It is highly recommended that this setting not be changed at runtime.  It is recommended that this setting be set once at design time, and not again.  Changing this setting at runtime may cause problems with finding or identifying users.


See Also

LogIn  Method

LocateUser Method


ChangePasswordCaption Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property ChangePasswordCaption: string;

Description

The ChangePassword Caption property specifies what the caption of the dialog box will be when the user changes his or her password.  This caption must have a certain format.  The default value of this property is:

"Change %s's Password...."

Notice the %s in the middle of the string.  The Security Guard will replace this %s with the name of the user being edited at run time.  For example:  If the caption is setup as shown above, and the UserID 4572 is being edited, the caption of the dialog box would read:

"Change 4572's Password..."

The caption which you setup must also have a %s somewhere in it which can be used for the users ID at runtime.  If you do not put a %s in the string an exception will be raised.


Example

The following would setup the Change Password dialog box caption to read: "Change Eddie's password if desired!" for user Eddie

KpKpSecurityGuard1.ChangePasswordCaption := 'Change %s's password if desired!';


See Also

Properties

LogIn Caption

Edit User Caption

Edit User List Caption

Change Password Caption

Methods

LogIn

Edit User

Edit User List

Change Password


DefaultEncryption Property

See Also

Applies to

TKpSecurityGuard component

Declaration

property DefaultEncryption: boolean;

Description

Default encryption is closely linked to the OnEncrypt event.  To begin with they are mutually exclusive.  If DefaultEncryption is set to True, then any event handlers attached to the OnEncrypt event will be detached.  If an event handler is attached to the OnEncrypt event, then the DefaultEncryption property will be set to False.

The security guard encrypts all passwords before dealing with them.  When a new password is entered, it is encrypted before it is stored in the SecurityTable.  Before the security guard checks a password, it encrypts it and then compares the encrypted form against the values in the Security Table.

There are two methods which can be used to encrypt the password.  The first is to use the DefaultEncryption method, which is easiest, but for which you have no control over how the password is encrypted. To use the default encryption algorithm, simply set the DefaultEncryption property to True.

The second is to use your own encryption algorithm.  To use your own encryption algorithm, simply attach the encryption code to the OnEncrypt event.  Anytime the SecurityGuard needs to encrypt a password, the OnEncrypt event will be triggered and the Password which needs to be encrypted will be passed in to the event handler.

It is recommended that you decide on ONE encryption algorithm at design time and stick to it.  Either use the DefaultEncryption, or use your own Algorithm.

DO NOT CHANGE IT AT RUNTIME.

The reason for this is that if you use one encryption algorithm, and setup some users, and then change the encryption algorithm, the users setup with the original encryption algorithm will no longer be valid in the system.  When the Security Guard goes to check a password, it will Encrypt the password with the new algorithm, and then compare it to the password in the SecurityTable which was setup with the original encryption algorithm.  It will determine that the two passwords are different, when in fact they are the same, just encrypted with two different encryption algorithms.


See Also

DoDefaultEncryption  Method

OnEncrypt  Event


EditUserCaption Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property EditUserCaption: string;

Description

The Edit User Caption property determines what the caption of the dialog box will be when the information for a specific user is being edited.  This caption must have a certain format.  The default value of this property is:

"Edit %s's User Information...."

Notice the %s in the middle of the string.  The Security will replace this %s with the name of the user being edited at run time.  For example:  If the caption is setup as shown above, and the UserID 4572 is being edited, the caption of the dialog box would read:

"Edit 4572's User Information..."

The caption which you setup must also have a %s somewhere in it which can be used for the Users ID at run time.  If you do not put a %s in the string an exception will be raised.


Example

The following would setup the Edit User dialog box caption to read: "Change Eddie's User Information if desired!" for user Eddie

KpSecurityGuard1.EditUserCaption := 'Change %s's User Information if desired!';


EditUserListCaption Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property EditUserListCaption: string;

Description

If the entire list of users is to be edited with the EditUserList method, this property determines what the caption of the dialog box will read.

The default value for this property is:

"Edit List of Users..."


Example

This example would setup the dialog box used to edit the list of users to have the following caption: "Edit current User List..."

KpSecurityGuard1.EditUserListCaption := "Edit current User List...";


Logged Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property Logged: boolean;

Description

The Logged property is Run-time and Read Only.  Test this property to determine if there is currently a user logged into the system.  This property is set to True when a user successfully logs into the system with the LogIn method, and is cleared again then the LogOut method is called.


Example

The following example would log a new user into the system, if one was not already logged in.

if NOT KpSecurityGuard1.Logged then

  KpSecurityGuard1.LogIn;

else

  ShowMessage( 'A user is already logged In' );


See Also

LogIn Method

LogOut Method


LoginCaption Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property LoginCaption: string;

Description

When the LogIn method is called, the dialog box which shows up, gets its caption from this property.

The default value for this property is:

"User LogIn Dialog ..."


Example

You might want to have a more customized message.  One which fit your application better than the default LogIn message.

KpSecurityGuard1.LoginCaption := 'Welcome to C++ Demolition Mania!!!!!';


NumberOfTries Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property NumberOfTries: integer;

Description

When the LogIn method is called, if the SecurityTable is setup correctly, the NumberOfTries property determines how many times the user can unsuccessfully try to LogIn before the LogIn process is aborted.

The default value for this property is 3.

This value is also used when the VerifyPassword method is called.


Example

At certain times of the day you might want to make it easier for users to break into the system... :-)

if Now > StrToDateTime( "5:00PM" ) then

  KpSecurityGuard1.NumberOfTries := 250

else

  KpSecurityGuard1.NumberOfTries := 3;


See Also

LogIn Method

VerifyPassword Method


Password Property

See Also

Applies to

TKpSecurityGuard component

Declaration

property Password: string;

Description

The Password property is Run-time and Read Only.   After a user logs into the system with the LogIn method, this property will contain the value of the Password entered in its encrypted form.

This property will only be populated if the SecurityTable, UserField and PasswordField properties are all setup correctly.

The property will be populated with the value from the PasswordField.

For information about encryption, please refer to the DefaultEncryption property or the OnEncrypt event.

Each time this property changes, all TKpGuardLists in the application will be notified, and their GuardAll methods may be called.


See Also

LogIn Method

DefaultEncryption Property

OnEncrypt Event


PasswordChar Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property PasswordChar: Char;

Description

The password char determines what character will be used instead of the real characters when a password is entered by the user.  This character will be used in the LogIn and VerifyPassword dialog boxes.

The default value for this property is the * symbol.


Example

The password char, may be something which you would let your users set.  Their choice might be stored in an INI file.

s := ini.ReadString( 'Prefs', 'Password Char', '*' );

KpSecurityGuard1.PasswordChar := s[ 1 ];


PasswordField Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property PasswordField: string;

Description

The password field property is important for use with certain functions of the SecurityGuard.  If the ShowPassword property is set to False, then this field becomes irrelevant.  However, if the ShowPassword property is set to True, and any function needing the password field is called, then this field must be a valid field of the SecurityTable.

Here are some typical functions which "can" use the Password Field.

•	LogIn

•	VerifyPassword

•	EditUser

•	EditUserList

•	ChangePassword

NOTE: The password field is used when it is available.  However it is not always required.  Only the methods which directly refer to passwords, such as ChangePassword,  MUST have this property specified.


Example

The following example sets up the PasswordField and then logs in a new user

KpSecurityGuard1.SecurityTable := Table1;

KpSecurityGuard1.UserField := 'User';

KpSecurityGuard1.PasswordField := 'Password';

KpSecurityGuard1.ShowPassword := True;

KpSecurityGuard1.LogIn;


See Also

SecurityTable Property

UserField Property

PasswordField Property

SecurityLevelField Property


PasswordLabel Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property PasswordLabel: string;

Description

The "Label" properties are a key element of the customizability of the SecurityGuard.  You can specify the key terms to use, and the system will replace all references to these terms with the values you specify.  For example:  Your application may not use Passwords.  They may be referred to as PIN's (personal identification numbers) or Secret Codes.  It would then be a problem if the LogIn dialog box popped up and asked: "Please enter your User ID and Password:".

Use this property to set the name of the Password.  Whatever is specified here will appear throughout the entire Security system.  If you set it to PIN, then any reference to Password will be replaced with PIN.


Example

You may want to have the user specify what he wants to call passwords.  His choice might be stored in an INI file.

KpSecurityGuard1.PasswordLabel := ini.ReadString( 'Prefs', 'PasswordLabel', 'PIN' );


See Also

UserLabel Property

PasswordLabel Property

SecurityLevelLabel Property


SecurityLevel Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property SecurityLevel: integer;

Description

The SecurityLevel property is Run-time and Read Only.  After a user successfully logs into the system with the LogIn method, the SecurityLevel property will contain the value of the SecurityLevel achieved by the user.

This property will only be populated if the SecurityTable, UserField, and SecurityLevelField are all specified and setup correctly.

If the SecurityLevelField is not specified a SecurityLevel of 0 will be assumed.  When the user logs out, the SecurityLevel will be set back to its initial value of -1;

The value will be taken from the SecurityLevelField of the SecurityTable.

The SecurityLevel can be set to anything from -1 to 32767

Each time this property changes, all TKpGuardLists in the application will be notified, and their GuardAll methods may be called.


Example

Show message depending on who has logged in

if KpSecurityGuard1.Logged then

  case KpSecurityGuard1.SecurityLevel of

    1:	ShowMessage( 'Standard User' );

    2:	ShowMessage( 'Manager' );

    3:	ShowMessage( 'Developer' );

    32767:	ShowMessage( 'GOD' );

  end;


SecurityLevelField Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property SecurityLevelField: string;

Description

The SecurityLevelField property is completely optional in all cases.  If it is present, when a user logs into the system with the LogIn method, the SecurityLevel property will be populated with the value found in this field.

If this field is specified it must be a valid field of the  SecurityTable, which must also be specified and setup correctly.  It must also be a numeric field with values which can be converted into Integers without raising an exception.


Example

The following example would setup the security table, LogIn a user, and check his security level

KpSecurityGuard1.SecurityTable := Table1;

KpSecurityGuard1.UserField := 'User';

KpSecurityGuard1.PasswordField := 'Password';

KpSecurityGuard1.SecurityLevelField := 'SecurityLevel';

if KpSecurityGuard1.LogIn then

  if KpSecurityGuard1.SecurityLevel > 10 then

    ShowMessage( 'Welcome: You have manager rights!' );


SecurityLevelLabel Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property SecurityLevelLabel: string;

Description

The "Label" properties are a key element of the customizability of the SecurityGuard.  You can specify the key terms to use, and the system will replace all references to these terms with the values you specify.  For example:  Your application may not have SecurityLevels.  They may be referred to as Access Levels.  It would then be a problem if the EditUser dialog box popped up and asked for the users Security Level.

Use this property to set the name of your SecurityLevel.  Each instance of SecurityLevel throughout the system will then be replaced with whatever you specify.


Example

The following would cause the system to turn all references to security level into Clearance ID

KpSecurityGuard1.SecurityLevelLabel := 'Clearance ID';


SecurityTable Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property SecurityTable: TTable;

Description

The SecurityTable property is the table which stores the list of Users and their passwords.  The SecurityGuard is designed to be able to use any table which you would like.  All you need to do is setup how to use it.  Any table which can be accessed with a TTable component can be used as the SecurityTable.

There are a few things to keep in mind, with this table.  If the SecurityTable is specified, it must be Active, and ready.  Also, At a minimum, the UserField must be specified.

The SecurityGuard will regularly look through this table for various tasks it need to complete.  Because of this, the actual TTable used, should not be used elsewhere in your application if you can help it.  If it is, there may be conflicts with the current record pointer.  You may be in the middle of an operation and suddenly find that the SecurityGuard has moved the record pointer to another record for some reason or another.

After you have decided on what table you would like to use, setup the UserField, PasswordField and SecurityLevelFields where applicable.

NOTE: The SecurityTable does not have to be keyed, however, the SecurityGuard will NOT allow two users to be added to the system with the same User ID.


ShowPassword Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property ShowPassword: boolean;

Description

The ShowPassword property is used to determine if the password portion of certain dialog boxes should be shown.  This property should be set to False unless the SecurityTable, and PasswordFields are setup correctly.

By setting this property to False, any Dialogs which use password information, will automatically modify themselves to make these fields invisible.  Password information will also then not be used when verifying a user in the SecurityTable.

By setting this property to True, you are telling the system to collect password information.


Example

This application does not need to check passwords Monday through Friday.  Passwords are only needed on the weekends

if GetDayOfWeek in [ dSaturday, dSunday ] then

  KpSecurityGuard1.ShowPassword := True

else

  KpSecurityGuard1.ShowPassword := False;


See Also

LogIn Method

EditUser Method

SecurityTable Property

PasswordField Property


StandardLogFile Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property StandardLogFile: string;

Description

The standard log file is a log of all of the messages passed to the MainLog method.  Each message is appended to the end of the file setup in this propert (file must be specified with full path).  If this file is setup incorrectly an exception will be raised.  If this line is omitted altogether, no log will be kept.

The MainLog method is triggered automatically for all of the events setup in the StandardLogOn property, however if you want to add lines to this log yourself, you can call the MainLog method directly.

The MainLog method takes one string parameter which is the message line to add to the log file.  It takes this message and pre-pends a date time stamp, and then appends the entire message to the end of the LogFile.

One line is created for each event.  The line has the following format

Date + Time + Message

For example:

05/01/99 - 10:19 AM:  User 4572 logged in

05/01/99 - 11:58 AM:  User 4572 logged out

05/01/99 - 02:31 PM:  User 1378 failed verify password

etc.


Example

Lets setup a system which uses a different log file for each day of the month, and which logs users logging in and out of the system only.

DecodeDate( Now, iYear, iMonth, iDay );

{Construct name of file}
sFile := 'C:\Log_' + IntToStr( iDay ) + '.LOG';

{Setup SecurityGuard log file}
KpSecurityGuard1.StandardLogFile := sFile;

KpSecurityGuard1.StandardLogOn := [ seLogIn, seLogOut ];


StandardLogOn Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property StandardLogOn : TSecurityEvents;

Description

The purpose of the StandardLogOn property is to determine which events will be stored in the StandardLogFile.


Status Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property Status: TStatus;

Description

The status property of the SecurityGuard is similar to the Enabled property of most components.  It specifies how the SecurityGuard should act.  If the SecurityGuard is sAtEase, then it will not perform its automated tasks.  But if it sAtAttention, then it will perform all of its duties.

If the SecurityGuard is sAtEase then the AutoVerify will NOT take place.


Example

The following will set the Security Guard At Attention.

KpSecurityGuard1.Status := sAtAttention;


See Also

AutoVerifyAfter Property


TStatus Type

Applies to

TKpSecurityGuard component

Declaration

TStatus = ( sAtAttention, sAtEase, sVerifying )

Description

The TStatus type defines the possible values of the Status property of the TKpSecurityGuard component.


User Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property User: string;

Description

The user property is Run-time and Read Only.  After a user logs in with the LogIn method, this property will contain the User ID of the user who logged in.

Each time this property changes, all TKpGuardLists in the application will be notified, and their GuardAll methods may be called.


Example

This example will log in a new user, Post the users name in the title bar of the application.

if KpSecurityGuard1.LogIn then

  Caption := 'C++ Demolition Mania: [' + KpSecurityGuard1.User + ']';

{Would result in the following caption if 4572 logged in:

C++ Demolition Mania: [4572]  }


UserField Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property UserField: string;

Description

The user field specifies which field in the SecurityTable has the UserID's in it.  This field is required anytime the SecurityTable is specified.


UserLabel Property

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property UserLabel: string;

Description

The "Label" properties are a key element of the customizability of the SecurityGuard.  You can specify the key terms to use, and the system will replace all references to these terms with the values you specify.  For example:  Your application may not have User IDs.  They may be referred to as ID Numbers, or just Names.  It would then be a problem if the LogIn dialog box asked "Please enter your User ID and Password".  when it should read "Please enter your Name and Password"

Use this property to set the name of your User ID's.  Each instance of User ID throughout the system will then be replaced with whatever you specify.


Example

The following example sets up the name of the User ID's from the Preferences INI file.

KpSecurityGuard1.UserLabel := ini.ReadString( 'Prefs', 'User Label', 'Name' );


Units

The KpSecure and the KpGrdLst units declare the two basic components used to manage security issues in DELPHI applications.

KpSecure.DCU Components

TKpSecurityGuard

KpGrdLst.DCU Components

TKpGuardList


AddNewUser Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function AddNewUser : boolean; virtual;

Description

Add new user simply inserts a record into the SecurityTable with the User ID "New User" and then allows the user to edit this record with the EditSpecificUser method.

NOTE: User can not save the User ID as "New User" .  If he tries an User exception will be raised, and he will be asked to try again.

AddNewUser returns True if user was successfully added, and otherwise it returns False.

An exception will be raised if:

•	SecurityTable not specified

•	UserField not specified


See Also

.EditSpecificUser Method


ChangePassword Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function ChangePassword: boolean;	virtual;

Description

ChangePassword simply calls the ChangeSpecificPassword method for the current user.

An exception will be raised if there is no user currently logged into the system.


Example

The following example checks if this is the first day of the month, and asks the user to change his password if it is.

DecodeDate( now, iYear, iMonth, iDay );

if iDay = 1 then

  KpSecurityGuard1.ChangePassword;


See Also

ChangeSpecificPassword Method


ChangeSpecificPassword Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function ChangeSepcificPassword( sUser : string ) : boolean;	virtual;

Description

ChangeSpecificPassword finds the sUser in the SecurityTable.  It then asks user for Old and New password.  If the old password is correct, if verifies the New Password.  If the New Password verifies, it encrypts it and stores it in the SecurityTable.

If the password is successfully updated, the function Returns True, otherwise the function returns False.

The ChangePassword method simply calls this method with the Current User passed in as the sUser parameter.

An exception is raised if:

•	The user specified in the sUser parameter does not exist

•	The SecurityTable is not specified correctly

•	The UserField is not specified correctly

•	The PasswordField is not specified correctly


See Also

ChangePassword Method

DefaultEncryption Property

OnEncrypt Event


CheckPassword Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function CheckPassword( sPassword : string ) : boolean;	virtual;

Description

The CheckPassword method is to be used in conjunction with the LocateUser method. CheckPassword takes a password (NOT ENCRYPTED), and checks it against the password in the current record of the SecurityTable.

To check a password for user XXX, call LocateUser( XXX ), and then call the CheckPassword method, passing in the password which needs to be checked.  The SecurityGuard will then automatically encrypt the password with either the DefaultEncryption method or the OnEncrypt event, and then compare it to the value found in the PasswordField for the current record.

CheckPassword returns True if the values are the same, and False if the values are different.

An exception will be raised if:

•	The SecurityTable is not specified correctly

•	The PasswordField is not specified correctly


Example

In this example we have a User: 4572, and a Password: 45D12KLL.  We would like to check if this is the correct password for the user.

with KpSecurityGuard1 do

  if LocateUser( '4572' ) then

   begin

    if CheckPassword( '45D12KLL' ) then

      ShowMessage( 'That is the correct password' )

    else

      ShowMessage( 'Incorrect password entered!' );

   end

  else  {otherwise user could not be found}

    ShowMessage( 'User: 4572 not in Security Table');


See Also

LocateUser Method


DeleteSpecificUser Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function DeleteSpecificUser( sUser : string ) : boolean;	virtual;

Description

Delete specific user locates sUser in the SecurityTable, and then deletes the record. The AllowDelete event will be triggered before the user is deleted, which will allow you to stop the user from being deleted if so desired.

NOTE: If the sUser being deleted is currently logged into the system, he will be logged out after the record is deleted.

This method is called by the DeleteUser method, which simply passes in the current user into sUser parameter.

DeleteSpecificUser returns True if the operation was successful.

An exception will be raised if:

•	The user specified in the sUser parameter does not exist

•	The SecurityTable is not specified correctly

•	The UserField is not specified correctly


See Also

DeleteUser Method

LocateUser Method


DeleteUser Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function DeleteUser: boolean;	virtual;

Description

The DeleteUser method simply calls DeleteSpecificUser for the current User logged into the system.

An exception will be raised if there are no users logged into the system.


Example

The following example, prompts to see if the user really wants to kill himself, and then it deletes the current user

if MsgDlg( 'Are you sure you would like to remove yourself from the ' +

'system???', mtConfirmation, [ mbYes, mbNo ], 0 ) = mrYes then

  KpSecurityGuard1.DeleteUser;


See Also

DeleteSpecificUser  Method


DoDefaultEncryption Method

See Also

Applies to

TKpSecurityGuard component

Declaration

procedure DoDefaultEncryption;

Description

This is a key element of Password encryption.  There are two methods for encrypting passwords.  Whenever the SecurityGuard needs to encrypt a password, it checks to see if the DefaultEncryption property is set to True.  If it is, then it uses its own default encryption algorithm to encrypt the password.  If this property is False, then it checks to see if an event handler has been attached to the OnEncrypt event.

DoDefaultEncryption is to be used in conjunction with this latter approach.  If you attach code to the OnEncrypt method, you do NOT necessarily have to provide an encryption algorithm.  The OnEncrypt method expects the password passed to the event to be encrypted.  However, if you call the DoDefaultEncryption method in the OnEncrypt event, it tells the Security Guard to use its own encryption algorithm.


See Also

DefaultEncryption Property

OnEncrypt Event


EditSpecificUser Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function EditSpecificUser( sUser : string ) : boolean;	virtual;

Description

This method allows you to edit information for a specific user, specified in the sUser parameter.  Before the information for user specified in sUser can be edited, the AllowEdit event is triggered to check if this user can be edited.

If AllowEdit does not dis-allow the user to be edited, then a dialog box is popped up for the sUser.  The User ID, Password and Security Level can all be modified.

When the user clicks OK, the AllowAdd event is triggered to make sure that the User ID chosen is not a reserved ID.

An exception will be raised if:

•	User specified in sUser does not exist in the SecurityTable

•	SecurityTable not specified correctly

•	UserField not specified correctly

NOTE: The SecurityTable does not have to be keyed, however, the SecurityGuard will NOT allow two users to be added to the system with the same User ID..

Function returns true if the changes were accepted in the SecurityTable.


See Also

EditUser Method

EditUserList Method

AllowEdit Event

AllowAdd Event


EditUser Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function EditUser: boolean;	virtual;

Description

The EditUser method simply calls EditSpecificUser for the current user logged into the system.

An exception will be raised if:

•	No user is currently logged into this system.


Example

This example will check if a user is logged into the system, and will then edit his user information.

if KpSecurityGuard1.Logged then

  KpSecurityGuard1.EditUser;


See Also

EditSpecificUser Method


EditUserList Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure EditUserList;	virtual;

Description

The EditUserList method edits all of the users specified in the Security Table.  It allows the user to Add, Edit and Delete users from this table.

There are four "Allow" events associated with these tasks.  Allow events pass an ID and a boolean variable by reference to the event handler, and allow it to set whether the specified event should be allowed to take place.  For example: before an ID can be deleted, it is passed to the AllowDelete event.  If the handler attached to this event sets the Allow parameter to False, the ID will NOT be deleted.

The first event is the AllowList event.  It will be called for each ID before it is listed in the EditUserList dialog box.  If you set the Allow parameter to False for a certain ID, it will not appear in this dialog box, as though it is not in the SecurityTable at all.  This might be helpful if you have ID's setup for managers, or debugging, that you do not want average user Joe to be able to edit.

The second event is the  AllowAdd event.  It will be triggered after the user as chosen to add a user and entered the information for the new user.  The SecurityGuard waits this long, so that it knows the ID which is to be added.  This ID is then passed to the AllowAdd event.  If you do not want to allow the ID to be added, set the Allow parameter to False.

The third event is the AllowDelete event.  It will be called any time the user chooses to delete a User.

The fourth and final allow event is the AllowEdit event.  It will be called before any ID can be edited.  Again, you may have manager ID's which you do not want the average Joe to be able to edit, but which you want to show to the user.

NOTE: The SecurityTable does not have to be keyed, however, the SecurityGuard will NOT allow two users to be added to the system with the same User ID..


Example

Following are 4 examples;  There is one example for each type of event handler

{*** Allow List}

procedure TForm1DLG.KpSecurityGuard1AllowList(Sender: TObject;

  var AllowEvent: Boolean; sIdent: string);

  {Do not show user XXX in edit box (It is an internal User ID)}

begin

  if sIdent = 'XXX' then AllowEvent := False;

end;	{METHOD: SecurityGaurd1AllowList}

{*** Allow Add}

procedure TForm1DLG.KpSecurityGuard1AllowAdd(Sender: TObject;

  var AllowEvent: Boolean; sIdent: string);

  {Do NOT allow the user to add an ID called 'ADMINISTRATOR'}

begin

  if sIdent = 'ADMINISTRATOR' then AllowEvent := False;

end;	{METHOD: KpSecurityGuard1AllowAdd}

{*** Allow Edit AND Allow Delete}

procedure TForm1DLG.KpSecurityGuard1AllowEdtDel(Sender: TObject;

  var AllowEvent: Boolean; sIdent: string);

  {Do not allow the user to delete user ID 'MANAGER'}

begin

  if sIdent = 'MANAGER' then AllowEvent := False;

end;	{METHOD: KpSecurityGuard1AllowEdtDel}


See Also

AllowList Event

AllowAdd Event

AllowDelete Event

AllowEdit Event

EditUser Method

EditSpecificUser Method


LocateUser Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function LocateUser( sUser : string ) : boolean;	virtual;

Description

LocateUser looks through the UserField of the SecurityTable and finds the record for sUser.

LocateUser returns True if the selected user was found, and False if the user could not be found.

An exception will be raised if:

•	SecurityTable is not specified correctly

•	User Field is not specified correctly


Example

The following example checks to see if user 4572 is still a user, and deletes him if he is.

if KpSecurityGuard1.LocateUser( '4572' ) then

  KpSecurityGuard1.DeleteSpecificUser( '4572' );


See Also

CheckPassword Method


Log Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure Log( seSecurityEvent : TSecurityEvent;
sMsg, sID1, sID2, sID3 : string;
iID1, iID2 : integer );

Description

The Log method and the LogResFmt method both trigger the OnSecurityAction event, and possibly call the MainLog method for the message sMsg.

MainLog is called if the SecurityEvent passed into the 1st parameter is setup in the StandardLogOn property.

Parameters

sMsg	- Message to Log

sID1	- String Identifier 1

sID2	- String Identifier 2

sID3	- String Identifier 3

iID1	- Integer Identifier 1

iID2	- Integer Identifier 2


Example

Lets say we want to create a log event for any user who logs into the system after 5:00 PM.  The following would trigger the OnSecurityAction event, passing in a message, formatted with the User ID who logged in.  It would also pass in the user's ID as the first sID parameter, and the time the user logged in in the second sID parameter.  There are no integers associated with this event, so both are set to 0.

SAfter5ID would be a Resource Identifier for a string which reads:
"User: %s logged in after 5!"

with KpSecurityGuard1 do

  if Now > StrToDateTime(  '5:00 PM' ) then

    LogResFmt( seLogIn, SAfter5ID, [ User ], User, StrToDateTime( now ), '', 0, 0 );


See Also

Log Method

LogResFmt Method

MainLog Method

StandardLogFile Property

OnSecurityAction Event


TSecurityEvent Type

Applies to

TKpSecurityGuard component

Declaration

TSecurityEvent = ( seEncrypt, seLogIn, seFailedLogIn, seVerifyPassword, seFailedVerifyPassword, seLogOut, seDeleteUser, seEditUser, seEditUserList, seChangeUser, seChangePassword, seChangeSecurityLevel, seChangeStatus, seUDUser, seUDPassword, seUDSecurityLevel );

Description

TSecurityEvent type is an enumerated list of all of the different types of events which can happen to the security guard.  It is used as the first parameter to the OnSecurityAction event, so that the event handler can determine what type of event has taken place.  The two methods Log, and LogResFmt, which trigger this event, also take a parameter of type TSecurityEvent, to specify what the event is that they are logging (the SecurityEvent passed to these two methods will be automatically passed on to the OnSecurityAction event.


LogResFmt Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure LogResFmt( seSecurityEvent : TSecurityEvent;
iMsgID : word; params : array of const;
sID1, sID2, sID3 : string;
iID1, iID2 : integer );

Description

The LogResFmt loads the string resource identified in the iMsgID Parameter, and formats it with the array of const parameters passed in as the second parameter.  It is then combined with the rest of the parameters (sID1, sID2 etc.) and passed directly to the Log method.

NOTE: If you are not working with RES files, you might want to call the Log method directly.


LogIn Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function LogIn: boolean;	virtual;

Description

The LogIn method is the most important method in the SecurityGuard.  It shows a standard LogIn dialog box when it is called.  The user is then expected to enter a UserID and Password before they can continue.  The Password Field will be invisible if the ShowPassword property is set to False.  If the SecurityTable is not specified, then anything the user enters will be accepted as valid.

If however, the SecurityTable is specified, then the UserID and password will be checked against the values in that table.  The number of incorrect tries the user has is specified in the NumberOfTries property.  If a the SecurityLevelField is specified, then the SecurityLevel property will be populated from this field.

If however, the SecurityLevelField is not setup, then a SecurityLevel of 0 will be assumed.  When the LogOut method is called the SecurityLevel is set to -1.

Each time the SecurityLevel property changes, all TKpGuardLists in the application will be notified, and their GuardAll methods may be called.

NOTE:	Any user logged into the system will be automatically logged out of the system when LogIn is called.

If the LogIn FAILS then the OnFailedLogIn event will be called.


See Also

LogOut Method

VerifyPassword Method

AutoVerifyAfter Property

OnFailedLogIn Event


LogOut Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure LogOut;	virtual;

Description

The LogOut method logs the current user out of the system.  It clears the User and Password  properties, and sets the SecurityLevel property to -1.


Example

The following example logs the current user out of the system and resets the application window caption.

procedure TForm1DLG.LogOut(Sender: TObject);

begin

  KpSecurityGuard1.LogOut;

  Caption := 'C++ Demolition Mania - []';

end;	{METHOD: LogOut}


See Also

LogIn Method


MainLog Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure MainLog( sMsg : string );

Description

The MainLog method is the method which maintains the StandardLogFile.  It adds a date time stamp to sMsg, and appends it to the bottom of the StandardLogFile.

The method is called automatically by the system for each event setup in the StandardLogOn property.

This method can be called directly by you if you would like to log an event in the Standard log file which might not otherwise be tracked.


Example

For this example, lets make a log of who is logged in at 5 every day.  This code might be attached to a OnTimer event of a TTimer component.

with TKpSecurityGuard1 do

  if now = StrToDateTime( "5:00 PM" ) then

    MainLog( User + ' is logged in at 5:00PM' );


UpdatePassword Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure UpdatePassword( sUser, sNewPass : string );

Description

The UpdatePassword method locates sUser in the SecurityTable, and updates his password to the password specified in sNewPass.
NOTE: sNewPass will be encrypted with the current encryption algorithm.  It should be passed in in its UN-ENCRYPTED form.


Example

For this example, assume we have a user, his id was 4572.  We have now changed his information and we want to update his information to the following:

ID = 4571, PASSWORD = 12X23X65, SECURITYLEVEL = 15

The following code would accomplish this:

UpdatePassword( '4572', '12X23X65' );

UpdateSecurityLevel( '4572', 15 );

UpdateUser( '4572', '4571' );


See Also

UpdateUser Method

UpdatePassword Method

UpdateSecurityLevel Method


UpdateSecurityLevel Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure UpdateSecurityLevel( sUser : string; iNewSecurityLevel : integer );

Description

The UpdateSecurityLevel method locates the user specified in sUser in the SecurityTable and changes his SecurityLevel to iNewSecurityLevel.

NOTE: iNewSecurityLevel must be greater than 0, and less than 32767.


UpdateUser Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

procedure UpdateUser( sUser, sNewUser : string );

Description

The UpdateUser method locates sUser in the SecurityTable, and updates his user id to the value specified in the sNewUser parameter.


VerifyPassword Method

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

function VerifyPassword: boolean;	virtual;

Description

The VerifyPassword Method, pops up a dialog box and requires that the user Re-Enter his password.  He has as many tries as are specified in the NumberOfTries property.

If the user can not re-enter his password this method will return False, and the OnFailedVerify event will be triggered.

This method is automatically called by the AutoVerifyAfter property.

An exception will be raised if:

•	User is not currently logged into the system

•	Security Table is not specified correctly

•	UserField is not specified correctly

•	PasswordField is not specified correctly


Example

In this example, there may be certain functions which you will not allow, without a re-verification of the users password.  Before deleting a user for example

procedure TForm1DLG.KpSecurityGuard1AllowDelete(Sender: TObject;

  var AllowEvent: Boolean; sIdent: String);

  {Do not allow the user to delete user without first verifying his password}

begin

  if NOT KpSecurityGuard1.VerifyPassword then AllowEvent := False;

end;	{METHOD: KpSecurityGuard1AllowDelete}


See Also

AutoVerifyAfter Property

LogIn Method


AllowAdd Event

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property AllowAdd: TAllowEvent;

Description

There are two times when the AllowAdd event is triggered.

The first is when a user is added to the system from the EditUserList function, the following steps take place:

1.	The Add button is clicked

2.	A dialog pops up and asks for the new users information

3.	The OK button is clicked to complete the operation.

At this point the AllowAdd event is triggered, and the User ID to be added, is passed into the sIdent parameter.

The second is when a user is edited using the EditSpecificUser method.  Again, the Security Guard waits until the information has been edited and the OK button is clicked.  When the OK button is clicked, the AllowAdd event is called.

The SecurityGuard waits this long so that the specific ID of the user is known.


See Also

AllowEvent Type

AllowDelete Event

AllowEdit Event

AllowList Event

EditUserList Method

EditSpecificUser Method

DeleteSpecificUser Method


TAllowEvent Type

Unit

KpSecure

Declaration

TAllowEvent = procedure( Sender : TObject;
  var AllowEvent : boolean; sIdent : string ) of Object;

Description

The TAllowEvent is called when a critical SecurityAction is about to take place for a certain User ID.  The UserID is passed into the event with a boolean variable passed in by reference.  The code attached to the event handler then has the ability to set this AllowEvent parameter to False to abort the operation.

For example, if a User ID is about to be deleted from the system, the AllowDelete event will be triggered, and the User ID will be passed to the event.  If the AllowEvent parameter is set to false, then the User ID will not be deleted.


AllowDelete Event

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property AllowDelete: TAllowEvent;

Description

Any time the DeleteSpecificUser method is called, the AllowDelete event is triggered, and the User ID to be deleted is passed to the event.  If the AllowEvent parameter is set to false by the event handler, then the user is NOT deleted.

This might be helpful if you have manager or debugging ID's, which you do not want the average user Joe to be able to delete.


Example

You might want to prompt before the user can delete a user from the system.  The following code would do this for you.

procedure TForm1DLG.KpSecurityGuard1AllowDelete

(Sender: TObject; var AllowEvent: Boolean; sIdent: String);

  {Only allow event if the user confirms deletion}

begin

  AllowEvent := MessageDLG(

      'Are you sure you would like to delete User ID: ' + sIdent + '?',

       mtConfirmation, [ mbYes, mbNo ], 0 ) = mrYes;

end;	{METHOD: KpSecurityGuard1AllowDelete}


AllowEdit Event

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property AllowEdit: TAllowEvent;

Description

Any time the EditSpecificUser method is called, the AllowEdit event is triggered, and the User ID which is to be edited is passed into the sIdent parameter.  If the AllowEvent parameter is set to False, then, the User ID's information will NOT be edited.


AllowList Event

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property AllowList: TAllowEvent;

Description

The AllowList event is triggered when the EditUserList method is called.  The EditUserList method pops up a list of User IDs from the SecurityTable.  As it iterates through this table, building the list of users, the AllowList event is triggered for each ID.  Any time the AllowList event sets the AllowEvent parameter to False, the ID which was passed in will NOT be added to the List.  (As though it is not in the SecurityTable at all)

This might be helpful if you have Managers or debugging User ID's which you do not want the average user Joe to know about or have access to.


OnEncrypt Event

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property OnEncrypt: TEncryptEvent;

Description

The OnEncrypt event is probably the most important event in the SecurityGuard.  This event allows you to specify your own encryption algorithm if you do not like the one which the SecurityGuard provides.

The SecurityGuard encrypts all passwords before it uses them.  Whenever it needs to encrypt a password, it uses one of two methods.  If the DefaultEncryption property is set to True, then the SecurityGuard will use its own internal encryption Algorithm.  If this property is False however, it checks the OnEncrypt event.  If there is an event handler attached to this event, it passes the password which needs encrypting into this event handler, which can then encrypt the password.

The changes to the password, which the event handler makes, are saved because the sPassword parameter is passed in by Reference.

NOTE:  The encryption algorithm you use, must create a password which can be stored in the security table.  There are certain characters which may not be allowed into a standard character fields of a database.


Example

The following example simply encrypts the password passed in by reversing the order of the characters.  It is a relatively simply encryption algorithm, but it should clearly demonstrate how the OnEncrypt event is used.

procedure TForm1DLG.KpSecurityGuard1Encrypt(

  Sender: TObject; var sPass: string);

  {Encrypt password sPass, by reversing the letters in the string}

  {"0123456789" passed in would return "9876543210"}

  var i : integer; s : string;

begin

  {initialize string s}

  s := '';

  {get sPass in reversed order}

  for i := Length( sPass ) DownTo 1 do

    s := s + sPass[ i ];

  {Put reversed string back into sPass}

  sPass := s;

end;	{METHOD: KpSecurityGuard1Encrypt}


See Also

DefaultEncryption Property

DoDefaultEncrypt Method

LogIn Method

VerifyPassword Method


TEncryptEvent Type

Unit

KpSecure

Declaration

TEncryptEvent = procedure(

  Sender : TObject; var sPass : string ) of Object;

Description

The TEncryptEvent type is used by the OnEncrypt event.  It takes two parameters. The first is the SecurityGuard which generated the event, and the second is the password which needs to be encrypted, passed in by reference.


OnFailedLogIn Event

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property OnFailedLogIn: TNotifyEvent;

Description

Anytime the LogIn method is called, and the user can not correctly log into the system, the OnFailedLogIn event is triggered.

You might want to take some kind of action in the event of a user not logging in correctly, such as incrementing the NumberOfTries property or some other measure.


Example

For this example we are going to assume that we will increment the NumberOfTries property by 1 every time a user fails the LogIn process.

procedure TForm1DLG.KpSecurityGuard1FailedLogIn(Sender: TObject);

  {Increment the NumberOfTries property if user fails LogIn}

begin

  with TKpSecurityGuard( Sender ) do

    NumberOfTries := NumberOfTries + 1;

end;  {METHOD: KpSecurityGuard1FailedLogIn}


See Also

LogIn Method

OnFailedLogIn Event

VerifyPassword Method

OnFailedVerify Event


TNotifyEvent Type

Unit

Classes

Declaration

TNotifyEvent = procedure( Sender: TObject ) of Object;

Description

The TNotifyEvent type is the type for events that have no parameters.  These events simply notify the component that a specific event occurred.  For example, the OnClick, which is type TNotifyEvent, notifies the control that a click event occurred on the control.

Both the OnFailedLogIn and OnFailedVerify events use this type.


OnFailedVerify Type

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property OnFailedVerify: TNotifyEvent;

Description

The OnFailedVerify event is very important if you are using the AutoVerifyAfter property.  If you use the VerifyPassword method directly, it returns a boolean value which allows you to take action if the user could not verify his password.  However, if the VerifyPassword method is called automatically by the AutoVerifyAfter property, to handle the case when the user can not verify his password, you must attach code to the OnFailedVerify event.

You might want to log the user out of  the system for example if he can't verify his password.


Example

This example will log the user out of the system in the event that he can not verify his password.

procedure TForm1DLG.KpSecurityGuard1FailedVerify(Sender: TObject);

  {Log user out of system if he can't verify password}

begin

  TKpSecurityGuard( Sender ).LogOut;

end;  {METHOD: KpSecurityGuard1FailedVerify}


See Also

LogIn Method

OnFailedLogIn Event

VerifyPassword Method

OnFailedVerify Event


OnSecurityAction Event

See Also	Example

Applies to

TKpSecurityGuard component

Declaration

property OnSecurityAction:   TSecurityActionEvent;

Description

The OnSecurityAction event is called for each event described in the TSecurityEvent types.

There are many different possible uses for this event.  You might want to create your own log file or database.  This event is the heart of the operation.  This event knows about everything which goes on in while the SecurityGuards on watch.

The parameters passed into the EventInfo parameter will be the message for the event, and then the specifics of the message.  If you look at the message you will be able to determine what will be passed into the EventInfo parameters.

For example: If the following message is passed into the sMsg field of the EventInfo parameter:

"User: 4572 logged in"

then the sID1 field of the EventInfo would be set to 4572.

All the other fields would be blank!

The reason for the rest of the fields in the EventInfo packet, is so that you can more easily work with the message at runtime.  You might want to just store the ID's of who logged in and when.  It would be a pain for you to have to parse the actual message, so the ID is already separated and passed into the sID1 parameter of the EventInfo packet.


TSecurityActionEvent Type

Applies to

TKpSecurityGuard component

Declaration

TSecurityActionEvent = procedure( Sender : TObject;

const SecurityEvent : TSecurityEvent; EventInfo : TEventInfo ) of Object;

Description

The TSecurityActionEvent is the event which is triggered for every event described in the TSecurityAction type.  Information about the event is passed in the EventInfo packet.


TEventInfo Type

Applies to

TKpSecurityGuard component

Declaration

TEventInfo = Record =

sMsg : string;

sID1, sID2, sID3 : string;

iID1, iID2 : integer;

end;	{TEventInfo}

Description

The EventInfo type packages the information about a SecurityEvent, so that can easily be passed to the SecurityAction event handler.


Using the SecurityGuard Component

Purpose

The TKpSecurityGuard and TKpGuardList provide complete application security management in 2 simple to use DELPHI components.  Protect every aspect of your programs with just a few lines of code.

The SecurityGuard is provides the user interface for the SecuritySystem, and the GuardList implements the protection.  The GuardList maintains a list of any visual controls on your form, and a securityLevel for each.  When a user logs into the SecurityGuard, he gets a SecurityLevel, which is passed to each of the GuardLists in the application.  They disable any controls which require a higher SecurityLevel than acheived.

Tasks

•	To setup the simplest security system:
The simplest form of the security system, is a TKpSecurityGuard alone, with no security table implemented.  When the LogIn method is called, the standard LogIn dialog box is displayed and will ask for a UserID and password, however, any UserID and password will be accepted.  It does not matter what they type.

•	To Restrict access as to who can login to the TKpSecurityGuard:
If you setup a SecurityTable, you can restrict access to users who are listed in that table.  To find out how to setup this table, refer to Setting Up the SecurityTable.  If you setup this table, you must at least specify the UserField.  If you do NOT specify the PasswordField, then you must set ShowPassword to False or an exception will be raised

•	To setup how passwords are encrypted:
Passwords can be encrypted using either th encryption algorythm specified by the SecurityGuard (DefaultEncryption) or you can attach your own code to the OnEncrypt event, and specify your own encryption algorythm.  If you attach code to the OnEncrypt event, you do not HAVE to specify your own encryption algorythm.  You might want to call DoDefaultEncryption which will encrypt the password with the internal routine again.

•	To run the DEMO:
The demo program allows you to see many of the Methods, Properties and events related to the TKpSecurityGuard and TKpGuardList in action.  To run it, simply open the DEMO.DPR located in the KpSGDemo\ directory wherever you installed the rest of the TKpSecurityGuard and TKpGuardList files.

•	For Technical Support
Kalliopi International will make itself available for technical support questions through Compuserve, either on the DELPHI Forum or directly through compuserve mail.

•	Send mail to Technical Support at 73523.342@COMPUSERVE.COM.


  TKpGuardList component

Properties	Methods

Unit

KpGrdLst

Description

TKpGuardList is a component which assists a TKpSecurityGuard, in guarding the visual controls on a form.  Controls are enabled and disabled based on the SecurityLevel of each user who logs into the SecurityGuard.

Each GuardList maintains a list of objects(visual controls).  Each object has a minimum SecurityLevel requirement and a TSecurityOption associated with it. The SecurityOption specified is soDefault, soEnabled or soVisible.

When the Guard or GuardAll method is called, a security level is passed to it, and the guard list uses checks this SecurityLevel against the minimum SecurityLevel associated with each object.  Depending on the SecurityOption of each object the following takes place:

SecurityOption	Min SecurityLevel Met	Min SecurityLevel Not Met

soDefault	See below.

soEnabled	Enabled set to TRUE	Enabled set to FALSE

soVisible	Visible set to TRUE	Visible set to FALSE

When the SecurityOption is set to soDefault, the DefaultProp property is used.  This property can be set at design time.

When a user logs into a TKpSecurityGuard, that SecurityGuard notifies all GuardLists of the SecurityLevel of the new user.  Each GuardList then calls its GuardAll for that new SecurityLevel.

The GuardList can be completely setup at runtime as follows:  Set the DefaultProp property to specify what should happen for objects setup with TSecurityOption soDefault.  NOTE:  DefaultProp can NOT be set to soDefault itself.  It must be set to either soEnabled or soVisible.

To check if an object is protected by the GuardList call the IsProtected function.  Call the Protect method to add an new object to the GuardList, and the UnProtect method to remove an object from the GuardList.

To check what SecurityOption is setup for a specific object in the GuardList, call the GetSecurityOption method.  GetSecurityOption will automatically replace soDefault values with the value of DefaultProp.  To get the ACTUAL SecurityOption (including soDefault), call GetRealSecurityOption.  To set the SecurityOption for an object, call SetRealSecurityOption.

To find out the minimum SecurityLevel for an object, call the GetSecurityLevel method.  To set a new minimum SecurityLevel for an object, call the SetSecurityLevel method.

To have the GuardList actually implement its protection on an object for a certain SecurityLevel, call the Guard method.  To have the GuardList implement its protection on all of the objects in its GuardList, for a certain SecurityLevel, call the GuardAll method.

To show the list of objects protected in a list box, call the ShowList method.


The Guard List - Properties
Properties

Run-time only	Key properties

DefaultProp	List	SecurityGuard

Count


The Guard List - Methods
Methods

  Key methods

GetRealSecurityOption	IsProtected	ShowList

GetSecurityLevel	Protect	UnProtect

GetSecurityOption	SetRealSecurityOption

Guard	SetSecurityLevel

GuardAll	Setup


TSecurityOption Type

Unit

KpGrdLst

Declaration

property TSecurityOption = ( soDefault, soEnabled, soVisible );

Description

The TSecurityOption type specifies which property of an object will be disabled if the MinimumSecurityLevel is not met.  This property will be disabled (or enabled) when the Guard or GuardAll methods of a TKpGuardList are called)

If soDefault is specified, then it uses whatever the DefaultProp property of the GuardList is set to.


Count Property

See Also	Example

Applies to

TKpGuardList component

Declaration

property Count: integer;

Description

The count property reports how many items are protected by the GuardList.  For pointers to the actual objects protected, refer to the List property.


Example

This example will build a list of the names of all objects protected in the GuardList.

with KpGuardList1 do

  for i := 0 to Count - 1 do

    ComboBox1.Items.Add( TComponent( List[ i ] ).Name );


See Also

Count Property

List Property


DefaultProp Property

Example

Applies to

TKpGuardList component

Declaration

property DefaultProp: TSecurityOption;

Description

Any GuardList object setup with the SecurityOption soDefault, will use the DefaultProp of the GuardList, to specify which property will be effected when the object is Guarded with the Guard or GuardAll methods.

With this, you can protect many objects with the soDefault SecurityOption.  Then you can specify all at once, whether those objects will be disabled, or made invisible when they are Guarded.  If at some point you decide you want to change your mind, you can simply change the DefaultProp property and all of the objects will be effected.

NOTE: This property can NOT be set to soDefault.  It must either be set to soEnabled or soVisible.


Example

Lets say, that if the user's SecurityLevel is less than 10, you want to make all of the soDefault objects invisible, but if it is greater than 10, you just want to disable the objects. The following code would accomplish this.

if KpGuardList.SecurityGuard.SecurityLevel < 10 then

  KpGuardList.DefaultProp := soVisible

else

  KpGuardList.DefaultProp := soEnabled;


List Property

See Also	Example

Applies to

TKpGuardList component

Declaration

property List[ i : integer ] : pointer;

Description

The list property provides read only access to the actual list of object protected by the GuardList.  You will have to use TypeCasting to access the pointers.  To find out how many items are in this list, refer to the Count property.

NOTE: The property editor for this event allows you to setup the entire GuardList at design time.


SecurityGuard Property

See Also	Example

Applies to

TKpGuardList component

Declaration

property SecurityGuard : TKpSecurityGuard;

Description

A GuardList can be linked to a specific SecurityGuard, or it can be set to nil.  If its value is nil, then ANY TIME a new user logs into the system, with the LogIn method of ANY SecurityGuard, the objects in the GuardList will be re-guarded using the SecurityLevel of the new user.

If this property is set to point to one specific SecurityGuard however, then only when a new user logs into that guard, will the objects be re-guarded.


Example

The following example creates a new form, and sets the GuardList on that form to use the SecurityGuard on the main form.

f := TNewForm.Create( Self );

f.KpGuardList1.SecurityGuard := KpSecurityGuard1;

KpSecurityGuard1.LogIn


See Also

Guard Method

GuardAll Method


GetRealSecurityOption Method

See Also	Example

Applies to

TKpGuardList component

Declaration

function GetRealSecurityOption( Obj : TObject ) : TSecurityOption;	virtual;

Description

Each object in the GuardList has an associated SecurityOption, which specifies what will happen when the object is Guarded.

GetRealSecurityOption returns exactly what the SecurityOption for Obj is, soDefault, soEnabled or soVisible.  If you want to know which property will actually be effected, call the GetSecurityOption( Obj ) method.

GetRealSecurityOption is different than the GetSecurityOption method.  GetSecurityOption will replace soDefault with the DefaultProp value if applicable.  What this means, is that if the Option for Obj is soDefault, and GetSecurityOption is called, soDefault will be replaced with whatever DefaultProp is set to.  GetRealSecurityOption, on the other hand, would simply return soDefault.

NOTE: An exception will be raised if Obj is not Protected.


Example

In this example we want to check if an object is going to use the default property, and if it is, then we are going to change it to use the enabled property.

if KpGuardList1.GetRealSecurityOption( mReps ) = soDefault then

  KpGuardList1.SetRealSecurityOption( mReps, soEnabled );


GetSecurityLevel Method

See Also	Example

Applies to

TKpGuardList component

Declaration

function GetSecurityLevel( Obj : TObject ) : integer;	virtual;

Description

GetSecurityLevel, looks up the Obj in the GuardList, and returns the minimum SecurityLevel needed, to have access to the object.

The SecurityLevel return will NOT be less than 0 o greater than 32767

NOTE: An exception will be raised if Obj is not Protected.


Example

The following example would read the minimum security level for a management report from an INI file, and would then specify this security level to the GuardList guarding the form.

if KpGuardList1.GetSecurityLevel( mManagementRep ) < 5 then

  begin

    i := ini.ReadInteger( 'Security', 'Monthly Summary', 15 );

    KpGuardList1.SetSecurityLevel( mManagementRep, i );

  end;


GetSecurityOption Method

See Also	Example

Applies to

TKpGuardList component

Declaration

function GetSecurityOption( Obj : TObject ): TSecurityOption;	virtual;

Description

GetSecurityOption looks up the Obj in the GuardList, and returns the SecurityOption associated with that object.  If the SecurityOption is soDefault, it replaces it with whatever the value of DefaultProp is.

To find out what the Actual or Real value of the SecurityOption associated with Obj is, call the GetRealSecurityOption method.

NOTE: An exception will be raised if Obj is not Protected.


Example

The following example checks if the Management report SecurityOption is soEnabled, and if it is, then it sets it to soDefault.

if KpGuardList.IsProtected( mManagementRep ) then

  if KpGuardList.GetSecurityOption( mManagementRep ) = soEnabled then

    KpGuardList.SetRealSecurityOption( mManagementRep, soDefault );


See Also

GetSecurityOption Method

GetRealSecurityOption Method

SetRealSecurityOption Method

GetSecurityLevel Method

SetSecurityLevel Method

IsProtected Method


Guard Method

See Also	Example

Applies to

TKpGuardList component

Declaration

procedure Guard( Obj : TObject; iValue : integer );	virtual;

Description

The guard method actually implements its protection on the specified Object, if the Objects Minimum SecurityLevel is higher than iValue.  iValue will usually be the SecurityLevel of the current user.  When the Guard method is called, if the SecurityLevel of the current user is not high enough for Obj, then the SecurityOption specified for that object will be disabled.

The Guard method is called by the GuardAll method.  It is called once for each object guarded by the GuardList.

NOTE: An exception will be raised if Obj is not Protected.


Example

The following example would protect the Management Report menu item with a SecurityLevel of 10 higher than the actual SecurityLevel of the current user.

with KpGuardList1 do

  if IsProtected( mManagementRep ) then

    Guard( mManagementRep, SecurityGuard.SecurityLevel + 10 );


See Also

GuardAll Method

IsProtected Method


GuardAll Method

See Also	Example

Applies to

TKpGuardList component

Declaration

procedure GuardAll( iValue : integer );	virtual;

Description

The GuardAll method simply calls the Guard method for each object guarded by the GuardList.


See Also

Guard Method

IsProtected Method


IsProtected Method

See Also	Example

Applies to

TKpGuardList component

Declaration

function IsProtected( Obj : TObject ) : boolean;	virtual;

Description

The IsProtected method is used to test if an object is protected by a GuardList.  If you are not sure if an object is still setup in the GuardList you can ask the GuardList with the IsProtected method.

You can Protect and object which is not currently protected, and you can UnProtect an object which is already setup.

It takes one parameter which is the Object to test for, and returns true if it was found, and false if it was not.


Example

The following example tests to see if a certain object is protected, and if it is, then it UnProtects it, and if it is not then it protects it.

if KpGuardList.IsProtected( mManagementRep ) then

  KpGuardList.UnProtect( mManagementRep )

else

  KpGuardList.Protect( mManagementRep, 9, soDefault );


See Also

IsProtected Method

Protect Method

UnProtect Method


Protect Method

See Also	Example

Applies to

TKpGuardList component

Declaration

procedure Protected( Obj : TObject; iValue : integer; soValue : TSecurityOption );	virtual;

Description

Protect adds the Object specified in the Obj parameter to the GuardList.  It sets up the iValue parameter as the Minimum SecurityLevel which is used by the Guard method to test if the object should be disabled or enabled.

If the minimum SecurityLevel is not met when the Guard method is called, then the SecurityOption (soValue) is used to determine which property to affect.


SetRealSecurityOption Method

See Also	Example

Applies to

TKpGuardList component

Declaration

procedure SetRealSecurityOption( Obj : TObject; soValue : TSecurityOption );	virtual;

Description

SetRealSecurityOption specifies what SecurityOption is to be associated with the Object passed to the Obj parameter.

NOTE: An exception will be raised if Obj is not Protected.


SetSecurityLevel Method

See Also	Example

Applies to

TKpGuardList component

Declaration

function SetSecurityLevel( Obj : TObject; iValue : integer );	virtual;

Description

SetSecurityLevel sets the minimum SecurityLevel needed by the Guard Method to allow access to the Object specified in the Obj parameter.

NOTE: The value of iValue can NOT be less than 0 or greater than 32767.  SecurityLevels for objects protected by the GuardList must conform to this convention.

NOTE: An exception will be raised if Obj is not Protected.


Setup Method

See Also	Example

Applies to

TKpGuardList component

Declaration

procedure Setup( Obj : TObject; iValue : integer; soValue : TSecurityOption );	virtual;

Description

Setup simply calls the SetSecurityLevel, and SetRealSecurityOption for the Object passed into the Obj parameter.

NOTE: An exception will be raised if Obj is not Protected.


Example

The following example simply sets both the SecurityOption and SecurityLevel for the Management report Menu item, at the same time.

KpGuardList.Setup( mManagementRep, 15, soVisible );


ShowList Method

Applies to

TKpGuardList component

Declaration

procedure ShowList( List : TListBox ); virtual;

Description

Show list puts the names of each object in the GuardList into the list box List.  The list box is cleared fist, and the selected item in the list is preserved if possible.


UnProtect Method

See Also	Example

Applies to

TKpGuardList component

Declaration

procedure UnProtect( Obj : TObject );	virtual;

Description

UnProtect removes the Object Obj from the GuardList.

NOTE: An exception will be raised if Obj is not Protected